Git3 Compat + gix speedup for GitPython - #2274

MCP Server Git 2026.10.19's unchanged suite exposes three regressions in
`Repo.rev_parse()`: `HEAD:` returns a root `Tree` without a path, so directory
listing fails, and a missing `HEAD:<path>` raises generic `BadName` instead of
the established tree lookup `KeyError`. All three tests pass with released
GitPython 3.2.1 and fail with both local backends before this correction.

Retain an empty path for successfully resolved root trees when Git's
`objectmode` atom or Gix's `RevisionSpec.path_and_mode()` omits that context.
Factor the existing Git-validated colon boundary query so missing paths use
the public backend-managed `Tree.join()` for missing-component diagnostics,
including nested paths and colons inside commit-message searches. Git/Gix
continue to resolve revisions and read trees; no storage or Git semantics are
implemented separately in Python. The diagnostic prefix resolver retains a
documented CLI fallback until GixPython exposes compatible failed-path context.

Add a scripted fixture and eight regression cases across SHA-1/SHA-256 and
files/reftable; all eight fail before the correction. The repository/revision
and downstream suites pass 184 tests, two skips and 14 subtests on CLI; adding
native backend parity tests passes 286 tests, two skips and 14 subtests on Gix.
MCP Server Git's full unchanged suite now passes all 186 tests on each backend.
Ruff lint/format, ShellCheck for the fixture, mypy for `git/repo/fun.py`, and
`git diff --check` pass with Python 3.12.15, Git 2.53.0 and GixPython 0.2.0.

sbxloop 2.1.36 explicitly opens its metadata repositories with
`Repo(..., expand_vars=False)` to keep repository paths literal. Removing the
constructor option during the storage migration breaks 91 unchanged upstream
cases before their Git queries run. Released GitPython 3.2.1 accepts the option.

Restore the `False` constructor argument, including its fourth positional
location, while retaining the branch's default literal environment-variable
behavior. Reject `True` with a clear `ValueError` directing callers to expand
inputs themselves. Initial tilde expansion and Git/Gix discovery remain as
before; this input compatibility does not restore automatic environment
expansion or introduce Python Git behavior. Document the limited restored
contract and the remaining breaking path/API behavior.

Add a fixture containing both a literal `$DOWNSTREAM_REPOSITORY` repository
and an expansion target. Four SHA-1/SHA-256 and files/reftable regressions fail
before the correction and verify literal contents, keyword/positional use,
the unchanged default, and rejected expansion afterwards. Repository, CLI
safety and downstream suites pass 189 tests, two skips and 14 subtests on each
backend. Ruff lint/format, ShellCheck for the fixture, mypy for
`git/repo/base.py` and `git diff --check` pass with Python 3.12.15,
Git 2.53.0 and GixPython 0.2.0.

Salt parses `git.__version__` when enabling its GitPython provider. Source
imports retain the build placeholder `"git"`, so an editable installation
reports valid distribution metadata but Salt rejects the provider and skips
its real fileserver tests.

Read the checkout's `VERSION` only when the public value is still unstamped.
Built wheels and source distributions continue to use the existing release
stamping; repository discovery and backend selection are unchanged.

The regression failed with `"git"` before this change. All 34 downstream
compatibility regressions pass with both CLI and Gix. Ruff lint/format,
mypy for `git/__init__.py`, and `git diff --check` pass.

Demisto SDK imports `Union` from `git` while registering validators. Released
GitPython exposes `typing.Union`; removing that incidental export prevents
its unchanged root test conftest and CLI command registration from importing.

Retain the explicit alias without changing wildcard exports or adding Git
behavior. This unblocks the existing caller while preserving the narrower
package namespace elsewhere.

The import regression failed before this change. All 35 downstream
compatibility cases pass on CLI and Gix. Ruff lint/format, mypy for
`git/__init__.py`, and `git diff --check` pass. Released GitPython 3.2.1
was force-installed and verified in site-packages for the downstream baseline.

The existing release stamper matches every line containing `__version__ =`.
A comparison with the version variable on the left is also matched, causing
it to replace the placeholder in the new editable-import guard. That would
incorrectly enable the source-tree `VERSION` lookup in a built wheel, which
does not ship that file.

Put the literal on the left of the guard so stamping changes only the public
assignment. Extend the existing isolated installation test to verify public
version parity with the running source checkout.

The isolated installation and version checks pass with both CLI and Gix;
Ruff lint/format and `git diff --check` pass. The full CLI suite also passes:
1,827 passed,162 skipped,1 xfailed and59 passed subtests.

Kas 5.5 temporarily changes Git identity and restores it with
`config["user"] = original_values`. The migrated parser removed inherited
mapping assignment, leaving cleanup broken although released GitPython 3.2.1
passes that exact caller check.

Validate the complete nonempty mapping before changing the file, then use
existing Git config section removal and value writes. This replaces duplicate
and obsolete options while retaining other sections. Each Git mutation locks
independently; replacement is not transaction-wide atomic.

Empty sections and `add_section()` remain unsupported by the available native
configuration APIs. Kas's three SSH validation failures are retained and
documented alongside the existing Airflow mirror-fetch adapter gap. No Git
serialization or successful empty-section result is implemented in Python.

All four new SHA-1/SHA-256, files/reftable regressions failed before the fix.
All 90 config/downstream cases pass on CLI and Gix; Ruff lint/format, mypy for
`git/config.py`, and `git diff --check` pass.

The PR #2274 Python 3.8 install/import checks failed on Linux, macOS and
Windows with `TypeError: 'ABCMeta' object is not subscriptable` while evaluating
`Mapping[str, Any]`. Import `Mapping` from `typing`, preserving the same runtime
mapping validation while supporting the declared Python 3.8 minimum. The source
import reproduced the failure before this correction and passes afterward with
Python 3.8.20, including evaluated method annotations. The config/downstream
modules pass all 90 tests on each backend; Ruff lint/format and changed-module
mypy pass. Hosted verification follows the branch push.

MkDocs RSS Plugin 1.19.0 imports `Optional` from `git` while importing its
actual utility module. Released GitPython 3.2.1 exposes `typing.Optional`,
whereas the migrated package renamed that import and prevents the plugin
from loading.

Restore the explicit public alias and use it for the existing `refresh()`
annotation. Wildcard exports and Git operations are unchanged.

The new import regression fails before the fix. All 40 downstream
compatibility cases pass on CLI and Gix; Ruff lint/format, mypy for
`git/__init__.py`, and `git diff --check` pass. A forced released baseline
proves the alias and actual plugin import in site-packages.

Port the regression from PR #2302 using the scripted repository fixtures.
Check ordinary, Unicode, DEL-containing and leading-space filenames with
both `core.quotePath` settings, including untracked dirty detection.

Validate every filename against NUL-delimited `git status` output before
querying GitPython. Both backends already preserve these paths: the CLI
uses NUL records and Gix uses its directory walk, so no production fix is
needed.

Both untracked-file tests pass with CLI and Gix, including two configuration
subtests. Ruff lint/format, ShellCheck and `git diff --check` pass.

Port PR #2301's regression for U+0085, U+2028 and U+2029 in filenames
with `core.quotePath=false`. Both backends raised `ValueError` because
`Commit.stats` and `Stats._list_from_string()` treated those characters as
record separators in Git's output.

Split only at LF and ignore empty records, preserving filenames and empty
commit results. Keep the existing Gix filename-quoting CLI fallback; this
change adapts Git's output and does not implement native diff behavior.
Clarify that fallback in `doc/gix-backend.md` and record the user-visible fix.

The scripted fixture creates root, modified and empty commits through Git.
Direct NUL-delimited `git diff-tree --numstat` and `--name-status` queries
validate the expected names, counts and change types before the GitPython
assertions. The regression fails before the fix with both backends; all 42
commit/statistics tests and 21 subtests pass afterward on each backend.
Ruff lint/format, changed-source mypy, ShellCheck and `git diff --check` pass.

Cover the configuration regressions from PRs #2305 and #2307 against actual
`git config` output. The current configuration facade already delegates
these operations to Git, so the valid cases pass without a runtime change.

Use scripted fixtures for a real home-relative conditional include and the
complete inline-header sample. Preserve native `HOME` and `USERPROFILE`
separators so the same test exercises the Windows path case on Windows.
Check both matching and nonmatching repositories and file/stream readers.
Also check adjacent headers, an escaped quote before `]`, and rejection of
unbalanced quotes, missing/stray brackets, malformed keys and sections.

Git accepts multiple section headers on one line but omits empty sections
from `git config list`. Reflect that output and the facade's documented
empty-section limitation instead of restoring a separate Python parser.
Document the existing `GIX-12` fallback without claiming native coverage.

Validation on macOS, Git 2.54.0, Python 3.12 and GixPython 0.2.0:

- All 11 added cases passed against the unchanged runtime.
- `test/test_config.py`: 62 passed with each of the CLI and Gix backends.
- `ruff check`, `ruff format --check`, `bash -n` and `git diff --check` passed.

Windows and Linux execution was not available for this local check.

Port the regression from PR #2303 for CR-only, space-only and tab-only
header lines. Each initial commit is created by `commit.sh`, accepted by
`git fsck --strict`, and projected by `git show` before comparing both
`Commit._deserialize()` and the public lazy commit reader. A forged
`Co-authored-by` header must stay outside the message and co-author list.

The existing LF-only header parser already passes these cases, so no
production fix is needed. Record GIX-31: GixPython 0.2.0 rejects CR/tab
header lines that Git 2.54.0 accepts. The tests preserve and verify the
existing native decoder diagnostic fallback; the space continuation
uses the existing GIX-30 late-encoding fallback.

Validation: all 41 tests and 24 subtests in `test/test_commit.py` pass
with both `GIT_PYTHON_BACKEND=cli` and `GIT_PYTHON_BACKEND=gix`.
`ruff check`, `bash -n` and `git diff --check` pass.

URLs read from `.gitmodules` were cloned and fetched as if a user had
provided them directly. Git rejects `protocol.file.allow=user` for
`git submodule update`, but `Submodule.update` accepted it on both backends.

Port the clone/fetch regression from PR #2304, with a scripted initial
state and live `git submodule update --init` / `--remote` baselines for
denied transfers, allowed transfers, and checked-out commits. Pass
`GIT_PROTOCOL_FROM_USER=0` to these CLI operations. Preserve the existing
explicit unsafe-protocol option and caller-provided clone environment.
Move the existing test config helper so local-submodule tests and tutorials
can request `protocol.file.allow=always` explicitly.

The regression failed on both backends before this change and passes on
both afterward against Git 2.54.0 and GixPython 0.2.0. The submodule,
no-fetch, and docs suites exercised 482 cases per backend; all 476 expected
passing cases passed after the affected docs fixture and host-signing case
were rerun with the isolated runner (5 skips, 1 expected failure).
Ruff lint/format, shellcheck, and `git diff --check` pass. Clone and fetch
remain CLI fallbacks; document the native API gaps without claiming Gix
implements the transport operation.

`RootModule.update` fetches a temporary remote when `.gitmodules` changes a
submodule URL. That fetch still treated the URL as user-provided, even after
ordinary submodule clone/fetch gained Git's non-user transport environment.
It could therefore access a denied local repository and replace `origin`
before the subsequent ordinary fetch finally rejected the transport.

Port PR #2304's separate changed-URL regression and apply the existing
`_transport_env()` helper to that initial fetch. The test compares denial
with real `git submodule sync` / `update --remote`, and checks unchanged
HEAD and original-remote preservation against a rejected Git fetch. Its
location-dependent initial repositories use the shared scripted fixtures.

Both source regressions failed on the original CLI and Gix backends. The
changed-URL test also failed independently after the ordinary update fix,
because `origin` had already changed. After this fix, 17 focused transport,
root-update, and no-fetch cases pass on each backend under the isolated
runner, using Git 2.54.0 and GixPython 0.2.0. Ruff lint/format, shellcheck,
and `git diff --check` pass. The fetch remains an explicit CLI operation.

Port PR #2306's regression against direct `git commit` and `git hook`
invocations. Before this fix, `Repo`'s automatic `GIT_DIR` binding made
Git treat the repository as explicitly selected: `IndexFile.commit()`
ran its pre-commit hook even when ordinary Git rejected dubious
ownership. The regression fails on both backends without the fix.

Retain the original discovery location and run `git rev-parse --git-dir`
before executing any commit hook, removing only the automatically bound
environment values. Remembering discovery supports external
`core.worktree` locations while matching `safe.directory` on ordinary,
bare, linked and separate-directory repositories. Explicit environment
or command-line repository selections retain Git's behavior, including
relative paths and consumption of one-shot options after failures.
Validate NUL arguments before starting either process.

The fixture tests verify rejection without hook side effects, Git's
safe-directory exemptions, and explicit repository-selection behavior.
Update the native-backend coverage test and GIX-23 documentation to
require two CLI processes per valid hook request, including missing
hooks. No independent ownership policy or native hook implementation
is introduced.

Validation: before the final option-preservation refinements, the full
index, repository and backend modules passed (CLI: 236 tests, 106 skips;
Gix: 338 tests, 4 skips; each with 19 passing subtests). Final focused
hook coverage passes with CLI (12 tests, 2 skips) and Gix (14 tests),
each with 9 passing subtests. A separate review independently reran the
ownership and repository-selection regressions on both backends.
`ruff check`, targeted `mypy`, fixture `bash -n` and `git diff --check`
pass. Windows and Linux were not run locally.

The five automated downstream profiles do not describe GitPython's wider
runtime, development and documentation consumers. Record four completed audit
batches of 31, 30, 39 and 15 distinct projects selected from September 2026
PyPI downloads plus known Git-focused users. The inventory covers every
identified current declared consumer within the top-15,000 snapshot and
348,530,835 monthly distribution requests, including extras. Downloads are
neither unique users nor attributable GitPython installations; the additions
and metadata limits also prevent a strict popularity top-115 claim.

Retain all four reports and JSON manifests under `test/downstream/`, linked
from its README. Preserve release and archive provenance, commands, import
proofs, backend results, baseline comparisons and coverage limits at their
original tested revisions. Sources, environments, logs, JUnit XML and
supplemental runners remain in ignored audit caches; a fresh environment must
reconstruct the disclosed harness. The five-profile CI runner remains the
maintained automation. Upstream tests, mocks and expectations are unchanged;
selected helpers, unused declarations and omitted application stacks are
identified explicitly. Gix selections retain documented Git CLI fallbacks.

Twelve separate fixes restore immutable index readers, global `-C` selection,
separate-Git-directory context, the `GitDB` selector, local tracking branches,
revision tree/path diagnostics, explicit literal-path construction, editable
version reporting, built-wheel version isolation, historical `Union` and
`Optional` imports, and nonempty configuration-section assignment.

Keep the remaining compatibility work visible. Kas 5.5 has three SSH setup
failures because `add_section()` cannot create an empty section through the
supported native APIs; downstream can use `set_value()` directly, while full
compatibility requires a native section-edit API. sbxloop 2.1.36 has five
constructor-subclass failures because native discovery validates metadata
before its overridden `config_reader()` runs; restoring that view requires
supported discovery/include controls without bypassing Git format validation.
Index mapping mutation and automatic environment expansion remain unsupported.
Airflow's ambiguous bare/mirror fetch results expose a separate GitPython
adapter gap: Git `fetch --porcelain` supplies full destination identities for
a future CLI adapter fix; Gix fetch remains a fallback until per-ref outcomes
are exposed. Other retained failures are downstream defects, baseline behavior
or explicitly recorded harness/coverage limits, not passing results.

Historical final full suites after the last production fix recorded 1,832
CLI passes and 1,934 Gix passes, with 162/60 skips, one xfail and 59 passed
subtests each. The last batch adds 117 upstream and 187 supplemental passes,
one baseline-inherited Dstack failure and two Jira skips per backend; its
separate MkNotebooks Binder build passes with both backends and the release.
Those historical results are not reruns on this rewritten stack.

Consolidate the four `docs:` record commits at the stack tip while retaining
the feature commit and twelve fixes in their original order. Resolve only
changelog context conflicts, keeping implementation entries with their fixes
and the subclass record here. Verify an identical final tree, unchanged
non-documentation patches, fourteen final commits with one top `docs:` commit,
115 distinct manifest projects, recorded CLI/Gix parity, local report links
and `git diff --check`. No new tests or hosted CI were run and no push occurred.

Replace the historical Gitoxide introduction in `README.md` with an
explanation of `GixPython` as Gitoxide's Python bindings and the experimental
`GitPython` backend. Describe reduced subprocess overhead and reuse of the
native repository handle, with a link to the backend benchmarks.

Show installation from this unreleased source checkout and selection through
`GIT_PYTHON_BACKEND` before imports. Explain automatic selection, explicit
CLI/Gix choices, CPython 3.11+, Git 2.52+, and the Rust 1.89+ and system linker
needed for Linux and Windows source builds of `GixPython` 0.3.0. Its default
hashing, compression and HTTPS dependencies use pure Rust. Retain CLI fallback
and compatibility limitations, linking the backend ledger and downstream audit.

Resolve replay against the introducing commit's 0.3.0 upgrade by keeping the
new README structure while updating its package version and source-build
prerequisites. No repository implementation changes are part of this commit.

Validation: the README activation example returned the same HEAD as
`git rev-parse HEAD`; local links and `git diff --check` passed. The complete
fast profile passed: configured pre-commit hooks, `mypy --python-version=3.12`,
`basedpyright --warnings`, `uv sync --all-extras --all-groups --dry-run`, and
vendored-package CI lint. Full tests, builds, documentation builds and
benchmarks were outside the requested fast profile.